<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Appendix A.  API Notes and Details</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Collections Tutorial" />
    <link rel="up" href="index.html" title="Berkeley DB Collections Tutorial" />
    <link rel="prev" href="Summary.html" title="Chapter 7.  Summary" />
    <link rel="next" href="UsingCollectionsAPI.html" title="Using the DB Java Collections API" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Appendix A. 
        API Notes and Details
    </th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="Summary.html">Prev</a> </td>
          <th width="60%" align="center"> </th>
          <td width="20%" align="right"> <a accesskey="n" href="UsingCollectionsAPI.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="appendix" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title"><a id="collectionOverview"></a>Appendix A. 
        API Notes and Details
    </h2>
          </div>
        </div>
      </div>
      <p>
        This appendix contains information useful to the collections programmer
        that is too detailed to easily fit into the format of a tutorial.
        Specifically, this appendix contains the following information:
    </p>
      <div class="itemizedlist">
        <ul type="disc">
          <li>
            <p>
                <a class="xref" href="collectionOverview.html#UsingDataBindings" title="Using Data Bindings">
        Using Data Bindings
    </a>
            </p>
          </li>
          <li>
            <p>
                <a class="xref" href="UsingCollectionsAPI.html" title="Using the DB Java Collections API">
        Using the DB Java Collections API
    </a>
            </p>
          </li>
          <li>
            <p>
                <a class="xref" href="UsingStoredCollections.html" title="Using Stored Collections">
        Using Stored Collections
    </a>
            </p>
          </li>
          <li>
            <p>
                <a class="xref" href="SerializedObjectStorage.html" title="Serialized Object Storage">
        Serialized Object Storage
    </a>
            </p>
          </li>
        </ul>
      </div>
      <div class="sect1" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a id="UsingDataBindings"></a>
        Using Data Bindings
    </h2>
            </div>
          </div>
        </div>
        <div class="toc">
          <dl>
            <dt>
              <span class="sect2">
                <a href="collectionOverview.html#SelectingBindingFormats">
            Selecting Binding Formats
        </a>
              </span>
            </dt>
            <dt>
              <span class="sect2">
                <a href="collectionOverview.html#RecordNumberBindings">Record Number Bindings</a>
              </span>
            </dt>
            <dt>
              <span class="sect2">
                <a href="collectionOverview.html#SelectingDataBindings">
            Selecting Data Bindings
        </a>
              </span>
            </dt>
            <dt>
              <span class="sect2">
                <a href="collectionOverview.html#ImplementingBindings">
            Implementing Bindings
        </a>
              </span>
            </dt>
            <dt>
              <span class="sect2">
                <a href="collectionOverview.html#UsingBindings">
            Using Bindings
        </a>
              </span>
            </dt>
            <dt>
              <span class="sect2">
                <a href="collectionOverview.html#SecondaryKeyCreators">
            Secondary Key Creators
        </a>
              </span>
            </dt>
          </dl>
        </div>
        <p>
        Data bindings determine how keys and values are represented as
        stored data (byte arrays) in the database, and how stored data is
        converted to and from Java objects.
    </p>
        <p>
        The selection of data bindings is, in general, independent of
        the selection of 
        <span> access methods and </span>
        collection views. In other
        words, any binding can be used with any 
        <span> access method or </span>
        collection.
        <span>
            One exception to this rule is described under 
            <a class="xref" href="collectionOverview.html#RecordNumberBindings" title="Record Number Bindings">Record Number Bindings</a>
            below.
        </span>
    </p>
        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
          <h3 class="title">Note</h3>
          <p>
            In this document, bindings are described in the
            context of their use for stored data in a database. However,
            bindings may also be used independently of a database to operate on
            an arbitrary byte array. This allows using bindings when data is to
            be written to a file or sent over a network, for example.
        </p>
        </div>
        <div class="sect2" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h3 class="title"><a id="SelectingBindingFormats"></a>
            Selecting Binding Formats
        </h3>
              </div>
            </div>
          </div>
          <p>
        For the key and value of each stored collection, you may select
        one of the following types of bindings.
    </p>
          <div class="informaltable">
            <table border="1" width="80%">
              <colgroup>
                <col />
                <col />
                <col />
              </colgroup>
              <thead>
                <tr>
                  <th>Binding Format</th>
                  <th>Ordered</th>
                  <th>Description</th>
                </tr>
              </thead>
              <tbody>
                <tr>
                  <td>
                    <a class="ulink" href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a>
                    
                </td>
                  <td>No</td>
                  <td>
                    The data is stored using a compact form of Java serialization,
                    where the class descriptions are stored separately in a catalog
                    database. Arbitrary Java objects are supported.
                </td>
                </tr>
                <tr>
                  <td>
                    <a class="ulink" href="../../java/com/sleepycat/bind/tuple/TupleBinding.html" target="_top">TupleBinding</a>
                    
                </td>
                  <td>Yes</td>
                  <td>
                    The data is stored using a series of fixed length primitive
                    values or zero terminated character arrays (strings). Class/type
                    evolution is not supported.
                </td>
                </tr>
                <tr>
                  <td>
                    <a class="ulink" href="../../java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a>
                    
                </td>
                  <td>Yes</td>
                  <td>
                    The data is a 32-bit integer stored in a platform-dependent format.
                </td>
                </tr>
                <tr>
                  <td>Custom binding format</td>
                  <td>User-defined</td>
                  <td>
                    The data storage format and ordering is determined by the
                    custom binding implementation.
                </td>
                </tr>
              </tbody>
            </table>
          </div>
          <p>
        As shown in the table above, the tuple format supports built-in ordering
        (without specifying a custom comparator), while the serial format does
        not. This means that when a specific key order is needed, tuples should
        be used instead of serial data. Alternatively, a custom Btree comparator should be
        specified using
        <code class="methodname">DatabaseConfig.setBtreeComparator()</code>. Note that
        a custom Btree comparator will usually execute more slowly than the
        default byte-by-byte comparison. This makes using tuples an attractive
        option, since they provide ordering along with optimal performance.
    </p>
          <p>
        The tuple binding uses less space and executes faster than the
        serial binding. But once a tuple is written to a database, the
        order of fields in the tuple may not be changed and fields may not
        be deleted. The only type evolution allowed is the addition of
        fields at the end of the tuple, and this must be explicitly
        supported by the custom binding implementation.
    </p>
          <p>
        The serial binding supports the full generality of Java
        serialization including type evolution. But serialized data can
        only be accessed by Java applications, its size is larger, and its
        bindings are slower to execute.
    </p>
        </div>
        <div class="sect2" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h3 class="title"><a id="RecordNumberBindings"></a>Record Number Bindings</h3>
              </div>
            </div>
          </div>
          <p>
            Any use of an access method with record number keys, and therefore any
            use of a stored list view, requires using
                    <a class="ulink" href="../../java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a>
                    
            as the key binding. Since Berkeley DB stores record number keys using
            a platform-dependent byte order, 
                    <a class="ulink" href="../../java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a>
                    
            is needed to store record numbers properly. See
            <span class="html"><a class="ulink" href="../../programmer_reference/am_conf_logrec.html" target="_top">logical record numbers</a> in</span>
                    the <em class="citetitle">Berkeley DB Programmer's Reference Guide</em>
            for more information on storing DB record numbers.
        </p>
          <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
            <h3 class="title">Note</h3>
            <p>
                You may not use
                    <a class="ulink" href="../../java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a>
                    
                except with record number keys, as determined by the access
                method. Using
                    <a class="ulink" href="../../java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a>
                    
                in other cases will create a database that is not portable
                between platforms. When constructing the stored collection, 
                the DB Java Collections API will throw an
                    <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/IllegalArgumentException.html" target="_top">IllegalArgumentException</a>
                    
                in such cases.
            </p>
          </div>
        </div>
        <div class="sect2" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h3 class="title"><a id="SelectingDataBindings"></a>
            Selecting Data Bindings
        </h3>
              </div>
            </div>
          </div>
          <p>
        There are two types of binding interfaces. Simple entry bindings
        implement the 
        <a class="ulink" href="../../java/com/sleepycat/bind/EntryBinding.html" target="_top">EntryBinding</a>
        
        interface and can be used for key or value objects. Entity bindings
        implement the 
        <a class="ulink" href="../../java/com/sleepycat/bind/EntityBinding.html" target="_top">EntityBinding</a>
        
        interface and are used for combined key and value objects called
        entities.
   </p>
          <p>
        Simple entry bindings map between the key or value data stored
        by Berkeley DB and a key or value object. This is a simple
        one-to-one mapping.
    </p>
          <p>
        Simple entry bindings are easy to implement and in some cases
        require no coding. For example, a 
        <a class="ulink" href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a>
        
        can be used for keys or values without writing any additional
        code. A tuple binding for a single-item tuple can also be used without
        writing any code; see the
           <a class="ulink" href="../../java/com/sleepycat/bind/tuple/TupleBinding.html#getPrimitiveBinding(java.lang.Class)" target="_top">TupleBinding.getPrimitiveBinding</a> 
           
        method.
    </p>
          <p>
        Entity bindings must divide an entity object into its key and
        value data, and then combine the key and value data to re-create
        the entity object. This is a two-to-one mapping.
    </p>
          <p>
        Entity bindings are useful when a stored application object
        naturally has its primary key as a property, which is very common.
        For example, an Employee object would naturally have an
        EmployeeNumber property (its primary key) and an entity binding
        would then be needed. Of course, entity bindings are more complex
        to implement, especially if their key and data formats are
        different.
    </p>
          <p>
        Note that even when an entity binding is used a key binding is
        also usually needed. For example, a key binding is used to create
        key objects that are passed to the 
        <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.html#get" target="_top">Map.get()</a>
        
        method. A key object is passed to this method even though it may
        return an entity that also contains the key.
    </p>
        </div>
        <div class="sect2" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h3 class="title"><a id="ImplementingBindings"></a>
            Implementing Bindings
        </h3>
              </div>
            </div>
          </div>
          <p>
        There are two ways to implement bindings. The first way is to
        create a binding class that implements one of the two binding
        interfaces, 
        <a class="ulink" href="../../java/com/sleepycat/bind/EntryBinding.html" target="_top">EntryBinding</a>
        
        or 
        <a class="ulink" href="../../java/com/sleepycat/bind/EntityBinding.html" target="_top">EntityBinding</a>.
        For tuple bindings and serial bindings there are a number of
        abstract classes that make this easier. For example, you can extend
        <a class="ulink" href="../../java/com/sleepycat/bind/tuple/TupleBinding.html" target="_top">TupleBinding</a>
        
        to implement a simple binding for a tuple key or value. Abstract
        classes are also provided for entity bindings and are named after
        the format names of the key and value. For example, you can extend
        <a class="ulink" href="../../java/com/sleepycat/bind/serial/TupleSerialBinding.html" target="_top">TupleSerialBinding</a>
        
        to implement an entity binding with a tuple key and serial
        value.
    </p>
          <p>
        Another way to implement bindings is with marshalling
        interfaces. These are interfaces which perform the binding
        operations and are implemented by the key, value or entity classes
        themselves. With marshalling you use a binding which calls the
        marshalling interface and you implement the marshalling interface
        for each key, value or entity class. For example, you can use
        <a class="ulink" href="../../java/com/sleepycat/bind/tuple/TupleMarshalledBinding.html" target="_top">TupleMarshalledBinding</a>
        
        along with key or value classes that implement the 
        <a class="ulink" href="../../java/com/sleepycat/bind/tuple/MarshalledTupleEntry.html" target="_top">MarshalledTupleEntry</a>
        
        interface.
    </p>
        </div>
        <div class="sect2" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h3 class="title"><a id="UsingBindings"></a>
            Using Bindings
        </h3>
              </div>
            </div>
          </div>
          <p>
        Bindings are specified whenever a stored collection is created.
        A key binding must be specified for map, key set and entry set
        views. A value binding or entity binding must be specified for map,
        value set and entry set views.
    </p>
          <p>
        Any number of bindings may be created for the same stored data.
        This allows multiple views over the same data. For example, a tuple
        might be bound to an array of values or to a class with properties
        for each object.
    </p>
          <p>
        It is important to be careful of bindings that only use a subset
        of the stored data. This can be useful to simplify a view or to
        hide information that should not be accessible. However, if you
        write records using these bindings you may create stored data that
        is invalid from the application's point of view. It is up to the
        application to guard against this by creating a read-only
        collection when such bindings are used.
    </p>
        </div>
        <div class="sect2" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h3 class="title"><a id="SecondaryKeyCreators"></a>
            Secondary Key Creators
        </h3>
              </div>
            </div>
          </div>
          <p>
        Secondary Key Creators are needed whenever database indices are
        used. For each secondary index 
        
        <span>
            (<a class="ulink" href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>)
        </span>
        a key creator is used to derive index key data from key/value data.
        Key creators are objects whose classes implement the 
        
        <a class="ulink" href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>
        
        interface.
    </p>
          <p>
        Like bindings, key creators may be implemented using a separate
        key creator class or using a marshalling interface. Abstract key
        creator classes and marshalling interfaces are provided in the
        com.sleepycat.bind.tuple and com.sleepycat.bind.serial
        packages.
    </p>
          <p>
        Unlike bindings, key creators fundamentally operate on key and
        value data, not necessarily on the objects derived from the data by
        bindings. In this sense key creators are a part of a database
        definition, and may be independent of the various bindings that may
        be used to view data in a database. However, key creators are not
        prohibited from using higher level objects produced by bindings,
        and doing so may be convenient for some applications. For example,
        marshalling interfaces, which are defined for objects produced by
        bindings, are a convenient way to define key creators.
    </p>
        </div>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="Summary.html">Prev</a> </td>
          <td width="20%" align="center"> </td>
          <td width="40%" align="right"> <a accesskey="n" href="UsingCollectionsAPI.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Chapter 7. 
		Summary
	 </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> 
        Using the DB Java Collections API
    </td>
        </tr>
      </table>
    </div>
  </body>
</html>
